StarIO for Windows®
StarIO is a high level programming tool that simplifies the development and creation
of software for Star printers. StarIO exposes an easy-to-use API that gives
you fundamental communications access to the printer. This API is supplied
pre-formed for all the most popular programming environments including Java and
.NET, and exposes the same functionality regardless of the printer model or the
communications interface you’re using.
Getting Started
The following explains how to setup your StarIO based development project:
Visual C++
To use StarIO in your Visual C++ project: include the StarIOPort.h header
file, link against the StarIOPort.lib library file, and finally run with
StarIOPort.dll in the application directory. C / C++ documentation
is written in-line with the function declarations in StarIOPort.h.
Visual C# and Visual Basic .NET
To use StarIO in your .NET project: reference the StarIO.dll .NET assembly
and run with both StarIO.dll and StarIOPort.dll in the application
directory. C# and VB.NET documentation is available in the StarIO.xml file.
Keep this XML file in the same directory as StarIO.dll and view the documentation
using Visual Studio’s IntelliSense and Object Browser features.
Java
To use StarIO in your Java project: simply add StarIO.jar to both the compile
(javac) and the runtime (java) classpath definitions and then run with StarIO.jar,
StarIOJ.dll, and StarIOPort.dll in the application
directory.
Java documentation is available in JavaDOC HTML format in the documentation directory.
VB 6
To use StarIO in your VB 6 project: simply add the StarIOPort.bas file as
a module and run with StarIOPort.dll in the application directory.
VB 6.0 documentation is written in-line with the function declarations in StarIOPort.bas.
Programming & Usage
Your usage of StarIO always begins by opening a port; in C programs this is done
via the OpenPort function, in .NET programs this is done by calling the Port
class’s static GetPort method, in Java programs this is done by calling the
StarIOPort class’s static getPort method.
All of these functions will, when successful, return a port handle (or object) back
to you.
When the port that you’ve requested could not be opened these functions will fail;
the C API’s OpenPort function will simply return 0 (zero) to indicate failure,
in the .NET scenario a PortException will be thrown, and in the Java scenario
a StarIOPortException will be thrown.
OpenPort will fail if the specified port does not exist, or if the specified
port settings cannot be applied to the port, or if any of the underlying OS system
calls fail themselves; these such failures generally indicate a serious failure
that you’ll want to investigate. OpenPort also fails when another process
has already opened the port that you’re attempting to use. This is a failure
that you can likely recover from.
In C programs you can distinguish between these two kinds of failures by calling
the GetLastError API - if the result is ERROR_ALREADY_EXISTS then you know
that another process currently has the port opened and that you should call the
OpenPort API again after waiting for a short while.
In C# and Java programs you can check the IsPortInUseFailure property of
the exception - if that property is set to true then you’ll want to retry the OpenPort
call.
Once you have successfully opened the port you can use all the other StarIO APIs.
In C programs all other APIs take the port handle as the first parameter.
In .NET and Java you simply call the port object’s methods.
When you have finished using the port you must close it. In C programs this
is done by calling the ClosePort API. In .NET programs this is done
by calling the Port.ReleasePort static method. In Java programs this
is done by calling the StarIOPort.releasePort static method. When writing
programs in one of the .NET languages or in Java, it is often convenient to close
the port in the finally part of a try / catch / finally
construct.
In general, it is easier to coordinate the various parts of your system if you close
ports as soon as you’re done using them, rather than holding them open indefinitely.
The other APIs function as described in the API documentation.
Port Names & Settings
The OpenPort function accepts three parameters: the
port name, the port settings, and the communication timeout. We’re explaining
the port naming and settings parameters here because these are very important:
USB - Printer Class Mode
- The port name parameter is formed by combining “USBPRN:” with your printer’s
Windows® printer queue name. For example, when you connect a Star TSP700II
USB printer the “Star TSP700II (TSP743II)” printer queue gets created for it.
To access this printer via StarIO you would call the OpenPort function with “USBPRN:Star
TSP700II (TSP743II)”.
- The port settings parameter must be the empty string: “”.
USB - Vendor Class Mode
- Three different port name parameter forms are accepted:
- “usbven:” instructs StarIO to open the first Star USB Vendor Class device
it finds. This is useful when your printer doesn’t have a USB serial number
set (which is the default state). When there is no USB serial number set,
connecting your printer to different USB ports on the computer will cause it to
be assigned varying COM port names - and this would otherwise complicate the use
of OpenPort. The “usbven:” port Name format eliminates this as a
concern by opening the first device it finds regardless of the COM port name it
has been assigned. When your deployment circumstance involves only a single
printer and that printer hasn’t been configured with a USB serial number, this is
probably your best choice.
- “usbven:snsnsnsn” causes StarIO to open the printer whose serial number
you’ve specified. This is useful in two scenarios: 1) to avoid new ports being
created when the printer is connected to the computer's different USB ports and
hibs, and 2) when you have multiple printers connected simultaneously. Note:
Star’s printers do not have USB serial numbers configured from the factory - you’ll
have to write a serial number into the device in order to use this facility.
- “usbven:COM4” or “usbven:COMx” causes StarIO to open communications with the printer
based on the COM port name it’s been natively assigned. You can determine
what name this is by looking in the Windows® Device Manager. Note: while this
facility is useful in some contexts, it may cause difficulties if the printer is
variously connected to different USB ports on the computer; each time it gets connected
to a different USB port it will be assigned a new COM port name (unless it has been
assigned a serial number - see above).
- The port settings parameter must be an empty string: “”.
Ethernet
- The port name parameter is formed by combining “TCP:” with your printer’s IP address.
For example, if your printer is established on the 192.168.1.102 address then you
would pass “TCP:192.168.1.102” in as the port name parameter.
- The port settings parameter must be the empty string: “”.
Parallel
- The port name parameter is simply the parallel port name like “LPT1” or
“LPT2” etc.
- The port settings parameter must be the empty string: “”.
Serial
- The port name parameter is simply the serial port name like “COM1” or
“COM2” etc.
- The port settings parameter is a comma-separated string containing the following
fields. When these fields are assembled into a single string it will take
on this form: “baudRate,parity,dataBits,stopBits,flowControl” as in “9600,n,8,1,n”.
- The baudRate field can be one of: “38400”, “19200”, “9600”,
“4800”, or “2400”.
- The parity field can be one of “n” for none, “e” for even, or
“o” for odd.
- The dataBits field can be one of “7” or “8”.
- The stopBits field must be “1”.
- The flowControl field can be “n” for no flow control or “h” for
hardware flow control.
Programming Samples
The following sample projects are included:
- Visual C++ 2005
- Visual C# 2005
- Visual Basic .NET 2005
- Java
- VB 6
Version Status
The following statements describe this release and any currently known problems.
You are encouraged to read and understand these so that your own deployment of this
solution can be made successful. We are currently working to resolve these problems; check back for updated versions of this document and of this
software.
- This software is currently supported on Windows 2000 Service Pack 4, Windows XP
Service Pack 2 and Service Pack 3, and on Vista and Vista Service Pack 1.
- This software is currently supported for use with these specific printer models:
TSP650, TSP700II, TUP900, TUP500, HSP7000
- This software may conflict with other software that shipped with or for your printer
model; if you choose to deploy this alongside other software, please conduct thorough
testing to confirm that no such conflicts exist.
- One or more of the sample projects has may have been updated. Please check
and download the latest
samples package.
- Please note that we conducted our testing of this software with the printer's NSB
function enabled.
- USB Vendor Class: The OpenPort function succeeds even when you pass in a malformed
port name (i.e. "USBVEN:BadName").
- Ethernet: The WritePort function succeeds even when the printer is offline.
This is because the Ethernet card continues to buffer incoming data regardless of
the printer's current status. Any data buffered while the printer is offline
will be printed once the printer becomes online again.
- USB Printer Class: Some printer models do not support the use of the ReadPort function.
You can check your model's support by running the any of the samples.
- Ethernet: The ResetDevice function is not supported and always returns false.
- Serial: The ResetDevice function works but always returns true, and does not report
failure even when the printer is turned
off or disconnected.
- Parallel: The ResetDevice function fails when used with some printer models - despite
the fact that the printer actually executes the reset. You can check if this
problem effects your printer model by running any of the samples.
- USB Printer Class: USB Printer Class does not work properly under Windows 2000,
and should not be used.
- TUP900 - USB Printer Class: Must be used in MODE=1 (DIPSW:1-6=OFF).
- Ethernet: The GetParsedStatus, BeginCheckedBlock, and GetOnlineStatus methods will
sometimes succeed even when the printer is disconnected or powered off. This
makes it difficult to know when the printer is in need of service. One possible
solution is to send the Star Line Mode <ETB> command at regular intervals,
confirming that the printer's ETB counter increments appropriately; if it does not,
you may assume that the printer is out-of-order.
- Serial: In order for the ResetDevice function to work, you must enable the interface
card's reset feature. This is done by setting the DIP switches found on the serial
interface card; refer to your printer's manual for specific instructions.
Version History
- Version 1.2.0.0
- Initial stand-alone release
Legal Information
Copyright 2008 Star Micronics Co., Ltd. All rights reserved. All trademarks
acknowledged. Windows® is a registered trademark of the Microsoft Corporation.